5.1. [BLOCK_REST] Blocking REST¶
Nel caso di implementazione tramite tecnologia REST, DEVONO essere seguite almeno le seguenti indicazioni:
- La specifica dell’interfaccia DEVE dichiarare tutti i codici di stato HTTP previsti dall’interfaccia, con il relativo schema della risposta, oltre che ad eventuali header HTTP restituiti;
- La specifica dell’interfaccia DEVE dichiarare lo schema della richiesta insieme ad eventuali header HTTP richiesti;
- Al passo (1) il fruitore DEVE utilizzare come verbo HTTP per l’esecuzione della chiamata a procedura il verbo HTTP method POST su un URL contenente gli ID interessati ed il nome del metodo;
- Al passo (2) l’erogatore DEVE utilizzare HTTP status 2xx a meno che non si verifichino errori.
5.1.1. Regole di processamento¶
Al termine del processamento della richiesta, l’erogatore DEVE fare uso dei codici di stato HTTP rispettando la semantica. In particolare, al ricevimento della richiesta da parte del fruitore, l’erogatore:
- DEVE verificare la validità sintattica e semantica dei dati in ingresso;
- DEVE, in caso di dati errati, restituire HTTP status 400 Bad Request fornendo nel body di risposta dettagli circa l’errore;
- DOVREBBE, in caso di rappresentazione semanticamente non corretta, ritornare HTTP status 422 Unprocessable Entity;
- DOVREBBE, se qualcuno degli ID nel path o nel body non esiste, restituire HTTP status 404 Not Found, indicando nel body di risposta quale degli ID è mancante;
- PUÒ, se ipotizza che la richiesta sia malevola, ritornare HTTP status 400 Bad Request o HTTP status 404 Not Found
- DEVE, in caso di errori non dipendenti dalla richiesta, restituire HTTP status 5xx rispettando la semantica degli stessi;
- DEVE, in caso di successo, restituire HTTP status 2xx inviando il risultato dell’operazione nel payload body.
NB: I messaggi di errore devono essere utili al client ma NON DEVONO rivelare dettagli tecnici e/o informazioni riservate.
5.1.2. Esempio¶
Specifica Servizio
https://api.ente.example/rest/nome-api/v1/RESTblocking.yaml
openapi: 3.0.1
info:
title: RESTblocking
version: "1.0"
description: |-
Questo file descrive semplicemente i metodi di un'API
e non indica tutte le informazioni di metadatazione che
normalmente vanno inserite.
license:
name: Apache 2.0 License
url: http://www.apache.org/licenses/LICENSE-2.0.html
paths:
/resources/{id_resource}/M:
post:
description: Esegue M
operationId: M
parameters:
- name: id_resource
in: path
required: true
schema:
type: integer
format: int32
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/MType'
responses:
200:
description: Esecuzione di M avvenuta con successo
content:
application/json:
schema:
$ref: '#/components/schemas/MResponseType'
400:
description: Richiesta non valida
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorMessage'
404:
description: Identificativo non trovato
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorMessage'
default:
description: |-
Errore inatteso. Non ritornare informazioni
sulla logica interna e/o non pertinenti all'interfaccia.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorMessage'
components:
schemas:
MType:
type: object
properties:
a:
$ref: '#/components/schemas/AComplexType'
b:
type: string
MResponseType:
type: object
properties:
c:
type: string
AComplexType:
type: object
properties:
a1s:
type: array
items:
type: integer
format: int32
a2:
type: string
ErrorMessage:
type: object
properties:
detail:
description: |
A human readable explanation specific to this occurrence of the
problem.
type: string
instance:
description: |
An absolute URI that identifies the specific occurrence of the problem.
It may or may not yield further information if dereferenced.
format: uri
type: string
status:
description: |
The HTTP status code generated by the origin server for this occurrence
of the problem.
exclusiveMaximum: true
format: int32
maximum: 600
minimum: 100
type: integer
title:
description: |
A short, summary of the problem type. Written in english and readable
for engineers (usually not suited for non technical stakeholders and
not localized); example: Service Unavailable
type: string
type:
default: about:blank
description: |
An absolute URI that identifies the problem type. When dereferenced,
it SHOULD provide human-readable documentation for the problem type
(e.g., using HTML).
format: uri
type: string
Di seguito un esempio di chiamata al metodo M.
Endpoint
https://api.ente.example/rest/nome-api/v1/resources/1234/M
- Request
POST /rest/nome-api/v1/resources/1234/M HTTP/1.1
Host: api.ente.example
Content-Type: application/json
{
"a": {
"a1s": [ 1, 2 ],
"a2": "RGFuJ3MgVG9vbHMgYXJlIGNvb2wh"
},
"b": "Stringa di esempio"
}
- Response HTTP status 200 OK
HTTP/1.1 200 OK
Content-Type: application/json
{"c": "risultato"}
HTTP/1.1 500 Internal Server Error
Content-Type: application/problem+json
{
"type": "https://apidoc.ente.example/probs/operation-too-long",
"status": 500,
"title": "L'operazione è durata troppo.",
"detail": "Il sistema non e' riuscito a completare in tempo l'operazione prevista."
}
- Response HTTP status 400 Bad Request
HTTP/1.1 400 Bad Request
Content-Type: application/problem+json
{
"type": "https://apidoc.ente.example/probs/invalid-a",
"status": 400,
"title": "L'attributo \`b\` ha un valore non valido.",
"detail": "L'attributo \`b\` dev'essere una stringa di lunghezza inferiore a 32 caratteri."
}
- Response HTTP status 404 Not Found
HTTP/1.1 404 Not Found
Content-Type: application/problem+json
{
"status": 404,
"title": "Risorsa non trovata."
}